<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Django at a glance &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../index.html" />
    <link rel="up" title="Getting started" href="index.html" />
    <link rel="next" title="Quick install guide" href="install.html" />
    <link rel="prev" title="Getting started" href="index.html" />



 
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../index.html">Home</a>  |
        <a title="Table of contents" href="../contents.html">Table of contents</a>  |
        <a title="Global index" href="../genindex.html">Index</a>  |
        <a title="Module index" href="../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="Getting started">previous</a>
     |
    <a href="index.html" title="Getting started" accesskey="U">up</a>
   |
    <a href="install.html" title="Quick install guide">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="intro-overview">
            
  <div class="section" id="s-django-at-a-glance">
<span id="django-at-a-glance"></span><h1>Django at a glance<a class="headerlink" href="#django-at-a-glance" title="Permalink to this headline">¶</a></h1>
<p>Because Django was developed in a fast-paced newsroom environment, it was
designed to make common Web-development tasks fast and easy. Here&#8217;s an informal
overview of how to write a database-driven Web app with Django.</p>
<p>The goal of this document is to give you enough technical specifics to
understand how Django works, but this isn&#8217;t intended to be a tutorial or
reference &#8211; but we&#8217;ve got both! When you&#8217;re ready to start a project, you can
<a class="reference internal" href="tutorial01.html"><em>start with the tutorial</em></a> or <a class="reference internal" href="../topics/index.html"><em>dive right into more
detailed documentation</em></a>.</p>
<div class="section" id="s-design-your-model">
<span id="design-your-model"></span><h2>Design your model<a class="headerlink" href="#design-your-model" title="Permalink to this headline">¶</a></h2>
<p>Although you can use Django without a database, it comes with an
<a class="reference external" href="http://en.wikipedia.org/wiki/Object-relational_mapping">object-relational mapper</a> in which you describe your database layout in Python
code.</p>
<p>The <a class="reference internal" href="../topics/db/models.html"><em>data-model syntax</em></a> offers many rich ways of
representing your models &#8211; so far, it&#8217;s been solving many years&#8217; worth of
database-schema problems. Here&#8217;s a quick example:</p>
<div class="highlight-python"><div class="snippet-filename">mysite/news/models.py</div>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>

<span class="k">class</span> <span class="nc">Reporter</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">full_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">70</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>              <span class="c"># __unicode__ on Python 2</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">full_name</span>

<span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span>
    <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span>
    <span class="n">content</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">()</span>
    <span class="n">reporter</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Reporter</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>              <span class="c"># __unicode__ on Python 2</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">headline</span>
</pre></div>
</div>
</div>
<div class="section" id="s-install-it">
<span id="install-it"></span><h2>Install it<a class="headerlink" href="#install-it" title="Permalink to this headline">¶</a></h2>
<p>Next, run the Django command-line utility to create the database tables
automatically:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> python manage.py migrate
</pre></div>
</div>
<p>The <a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><tt class="xref std std-djadmin docutils literal"><span class="pre">migrate</span></tt></a> command looks at all your available models and creates
tables in your database for whichever tables don&#8217;t already exist, as well as
optionally providing <a class="reference internal" href="../topics/migrations.html"><em>much richer schema control</em></a>.</p>
</div>
<div class="section" id="s-enjoy-the-free-api">
<span id="enjoy-the-free-api"></span><h2>Enjoy the free API<a class="headerlink" href="#enjoy-the-free-api" title="Permalink to this headline">¶</a></h2>
<p>With that, you&#8217;ve got a free, and rich, <a class="reference internal" href="../topics/db/queries.html"><em>Python API</em></a>
to access your data. The API is created on the fly, no code generation
necessary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Import the models we created from our &quot;news&quot; app</span>
<span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">news.models</span> <span class="kn">import</span> <span class="n">Reporter</span><span class="p">,</span> <span class="n">Article</span>

<span class="c"># No reporters are in the system yet.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<span class="p">[]</span>

<span class="c"># Create a new Reporter.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span> <span class="o">=</span> <span class="n">Reporter</span><span class="p">(</span><span class="n">full_name</span><span class="o">=</span><span class="s">&#39;John Smith&#39;</span><span class="p">)</span>

<span class="c"># Save the object into the database. You have to call save() explicitly.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>

<span class="c"># Now it has an ID.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">id</span>
<span class="mi">1</span>

<span class="c"># Now the new reporter is in the database.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<span class="p">[</span><span class="o">&lt;</span><span class="n">Reporter</span><span class="p">:</span> <span class="n">John</span> <span class="n">Smith</span><span class="o">&gt;</span><span class="p">]</span>

<span class="c"># Fields are represented as attributes on the Python object.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">full_name</span>
<span class="s">&#39;John Smith&#39;</span>

<span class="c"># Django provides a rich database lookup API.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="o">&lt;</span><span class="n">Reporter</span><span class="p">:</span> <span class="n">John</span> <span class="n">Smith</span><span class="o">&gt;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">full_name__startswith</span><span class="o">=</span><span class="s">&#39;John&#39;</span><span class="p">)</span>
<span class="o">&lt;</span><span class="n">Reporter</span><span class="p">:</span> <span class="n">John</span> <span class="n">Smith</span><span class="o">&gt;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">full_name__contains</span><span class="o">=</span><span class="s">&#39;mith&#39;</span><span class="p">)</span>
<span class="o">&lt;</span><span class="n">Reporter</span><span class="p">:</span> <span class="n">John</span> <span class="n">Smith</span><span class="o">&gt;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Reporter</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
    <span class="o">...</span>
<span class="n">DoesNotExist</span><span class="p">:</span> <span class="n">Reporter</span> <span class="n">matching</span> <span class="n">query</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">exist</span><span class="o">.</span>

<span class="c"># Create an article.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">date</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">a</span> <span class="o">=</span> <span class="n">Article</span><span class="p">(</span><span class="n">pub_date</span><span class="o">=</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">(),</span> <span class="n">headline</span><span class="o">=</span><span class="s">&#39;Django is cool&#39;</span><span class="p">,</span>
<span class="o">...</span>     <span class="n">content</span><span class="o">=</span><span class="s">&#39;Yeah.&#39;</span><span class="p">,</span> <span class="n">reporter</span><span class="o">=</span><span class="n">r</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">a</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>

<span class="c"># Now the article is in the database.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Article</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<span class="p">[</span><span class="o">&lt;</span><span class="n">Article</span><span class="p">:</span> <span class="n">Django</span> <span class="ow">is</span> <span class="n">cool</span><span class="o">&gt;</span><span class="p">]</span>

<span class="c"># Article objects get API access to related Reporter objects.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span> <span class="o">=</span> <span class="n">a</span><span class="o">.</span><span class="n">reporter</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">full_name</span>
<span class="s">&#39;John Smith&#39;</span>

<span class="c"># And vice versa: Reporter objects get API access to Article objects.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">article_set</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<span class="p">[</span><span class="o">&lt;</span><span class="n">Article</span><span class="p">:</span> <span class="n">Django</span> <span class="ow">is</span> <span class="n">cool</span><span class="o">&gt;</span><span class="p">]</span>

<span class="c"># The API follows relationships as far as you need, performing efficient</span>
<span class="c"># JOINs for you behind the scenes.</span>
<span class="c"># This finds all articles by a reporter whose name starts with &quot;John&quot;.</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">Article</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">reporter__full_name__startswith</span><span class="o">=</span><span class="s">&#39;John&#39;</span><span class="p">)</span>
<span class="p">[</span><span class="o">&lt;</span><span class="n">Article</span><span class="p">:</span> <span class="n">Django</span> <span class="ow">is</span> <span class="n">cool</span><span class="o">&gt;</span><span class="p">]</span>

<span class="c"># Change an object by altering its attributes and calling save().</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">full_name</span> <span class="o">=</span> <span class="s">&#39;Billy Goat&#39;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>

<span class="c"># Delete an object with delete().</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">r</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="s-a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house">
<span id="a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house"></span><h2>A dynamic admin interface: it&#8217;s not just scaffolding &#8211; it&#8217;s the whole house<a class="headerlink" href="#a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house" title="Permalink to this headline">¶</a></h2>
<p>Once your models are defined, Django can automatically create a professional,
production ready <a class="reference internal" href="../ref/contrib/admin/index.html"><em>administrative interface</em></a> &#8211;
a Web site that lets authenticated users add, change and delete objects. It&#8217;s
as easy as registering your model in the admin site:</p>
<div class="highlight-python"><div class="snippet-filename">mysite/news/models.py</div>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>

<span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">pub_date</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateField</span><span class="p">()</span>
    <span class="n">headline</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span>
    <span class="n">content</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">()</span>
    <span class="n">reporter</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Reporter</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><div class="snippet-filename">mysite/news/admin.py</div>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.contrib</span> <span class="kn">import</span> <span class="n">admin</span>

<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">models</span>

<span class="n">admin</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Article</span><span class="p">)</span>
</pre></div>
</div>
<p>The philosophy here is that your site is edited by a staff, or a client, or
maybe just you &#8211; and you don&#8217;t want to have to deal with creating backend
interfaces just to manage content.</p>
<p>One typical workflow in creating Django apps is to create models and get the
admin sites up and running as fast as possible, so your staff (or clients) can
start populating data. Then, develop the way data is presented to the public.</p>
</div>
<div class="section" id="s-design-your-urls">
<span id="design-your-urls"></span><h2>Design your URLs<a class="headerlink" href="#design-your-urls" title="Permalink to this headline">¶</a></h2>
<p>A clean, elegant URL scheme is an important detail in a high-quality Web
application. Django encourages beautiful URL design and doesn&#8217;t put any cruft
in URLs, like <tt class="docutils literal"><span class="pre">.php</span></tt> or <tt class="docutils literal"><span class="pre">.asp</span></tt>.</p>
<p>To design URLs for an app, you create a Python module called a <a class="reference internal" href="../topics/http/urls.html"><em>URLconf</em></a>. A table of contents for your app, it contains a simple
mapping between URL patterns and Python callback functions. URLconfs also serve
to decouple URLs from Python code.</p>
<p>Here&#8217;s what a URLconf might look like for the <tt class="docutils literal"><span class="pre">Reporter</span></tt>/<tt class="docutils literal"><span class="pre">Article</span></tt>
example above:</p>
<div class="highlight-python"><div class="snippet-filename">mysite/news/urls.py</div>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">patterns</span>

<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">views</span>

<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">&#39;&#39;</span><span class="p">,</span>
    <span class="p">(</span><span class="s">r&#39;^articles/(\d{4})/$&#39;</span><span class="p">,</span> <span class="n">views</span><span class="o">.</span><span class="n">year_archive</span><span class="p">),</span>
    <span class="p">(</span><span class="s">r&#39;^articles/(\d{4})/(\d{2})/$&#39;</span><span class="p">,</span> <span class="n">views</span><span class="o">.</span><span class="n">month_archive</span><span class="p">),</span>
    <span class="p">(</span><span class="s">r&#39;^articles/(\d{4})/(\d{2})/(\d+)/$&#39;</span><span class="p">,</span> <span class="n">views</span><span class="o">.</span><span class="n">article_detail</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The code above maps URLs, as simple <a class="reference external" href="http://docs.python.org/2/howto/regex.html">regular expressions</a>, to the location of
Python callback functions (&#8220;views&#8221;). The regular expressions use parenthesis to
&#8220;capture&#8221; values from the URLs. When a user requests a page, Django runs
through each pattern, in order, and stops at the first one that matches the
requested URL. (If none of them matches, Django calls a special-case 404 view.)
This is blazingly fast, because the regular expressions are compiled at load
time.</p>
<p>Once one of the regexes matches, Django imports and calls the given view, which
is a simple Python function. Each view gets passed a request object &#8211;
which contains request metadata &#8211; and the values captured in the regex.</p>
<p>For example, if a user requested the URL &#8220;/articles/2005/05/39323/&#8221;, Django
would call the function <tt class="docutils literal"><span class="pre">news.views.article_detail(request,</span>
<span class="pre">'2005',</span> <span class="pre">'05',</span> <span class="pre">'39323')</span></tt>.</p>
</div>
<div class="section" id="s-write-your-views">
<span id="write-your-views"></span><h2>Write your views<a class="headerlink" href="#write-your-views" title="Permalink to this headline">¶</a></h2>
<p>Each view is responsible for doing one of two things: Returning an
<a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> object containing the content for the
requested page, or raising an exception such as <a class="reference internal" href="../topics/http/views.html#django.http.Http404" title="django.http.Http404"><tt class="xref py py-class docutils literal"><span class="pre">Http404</span></tt></a>.
The rest is up to you.</p>
<p>Generally, a view retrieves data according to the parameters, loads a template
and renders the template with the retrieved data. Here&#8217;s an example view for
<tt class="docutils literal"><span class="pre">year_archive</span></tt> from above:</p>
<div class="highlight-python"><div class="snippet-filename">mysite/news/views.py</div>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.shortcuts</span> <span class="kn">import</span> <span class="n">render</span>

<span class="kn">from</span> <span class="nn">.models</span> <span class="kn">import</span> <span class="n">Article</span>

<span class="k">def</span> <span class="nf">year_archive</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">year</span><span class="p">):</span>
    <span class="n">a_list</span> <span class="o">=</span> <span class="n">Article</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">pub_date__year</span><span class="o">=</span><span class="n">year</span><span class="p">)</span>
    <span class="n">context</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;year&#39;</span><span class="p">:</span> <span class="n">year</span><span class="p">,</span> <span class="s">&#39;article_list&#39;</span><span class="p">:</span> <span class="n">a_list</span><span class="p">}</span>
    <span class="k">return</span> <span class="n">render</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="s">&#39;news/year_archive.html&#39;</span><span class="p">,</span> <span class="n">context</span><span class="p">)</span>
</pre></div>
</div>
<p>This example uses Django&#8217;s <a class="reference internal" href="../topics/templates.html"><em>template system</em></a>, which has
several powerful features but strives to stay simple enough for non-programmers
to use.</p>
</div>
<div class="section" id="s-design-your-templates">
<span id="design-your-templates"></span><h2>Design your templates<a class="headerlink" href="#design-your-templates" title="Permalink to this headline">¶</a></h2>
<p>The code above loads the <tt class="docutils literal"><span class="pre">news/year_archive.html</span></tt> template.</p>
<p>Django has a template search path, which allows you to minimize redundancy among
templates. In your Django settings, you specify a list of directories to check
for templates with <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATE_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">TEMPLATE_DIRS</span></tt></a>. If a template doesn&#8217;t exist in the
first directory, it checks the second, and so on.</p>
<p>Let&#8217;s say the <tt class="docutils literal"><span class="pre">news/year_archive.html</span></tt> template was found. Here&#8217;s what that
might look like:</p>
<div class="highlight-html+django"><div class="snippet-filename">mysite/news/templates/news/year_archive.html</div>
<div class="highlight"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>Articles for <span class="cp">{{</span> <span class="nv">year</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="nt">&lt;h1&gt;</span>Articles for <span class="cp">{{</span> <span class="nv">year</span> <span class="cp">}}</span><span class="nt">&lt;/h1&gt;</span>

<span class="cp">{%</span> <span class="k">for</span> <span class="nv">article</span> <span class="k">in</span> <span class="nv">article_list</span> <span class="cp">%}</span>
    <span class="nt">&lt;p&gt;</span><span class="cp">{{</span> <span class="nv">article.headline</span> <span class="cp">}}</span><span class="nt">&lt;/p&gt;</span>
    <span class="nt">&lt;p&gt;</span>By <span class="cp">{{</span> <span class="nv">article.reporter.full_name</span> <span class="cp">}}</span><span class="nt">&lt;/p&gt;</span>
    <span class="nt">&lt;p&gt;</span>Published <span class="cp">{{</span> <span class="nv">article.pub_date</span><span class="o">|</span><span class="nf">date</span><span class="s2">:&quot;F j, Y&quot;</span> <span class="cp">}}</span><span class="nt">&lt;/p&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Variables are surrounded by double-curly braces. <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">article.headline</span> <span class="pre">}}</span></tt>
means &#8220;Output the value of the article&#8217;s headline attribute.&#8221; But dots aren&#8217;t
used only for attribute lookup. They also can do dictionary-key lookup, index
lookup and function calls.</p>
<p>Note <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">article.pub_date|date:&quot;F</span> <span class="pre">j,</span> <span class="pre">Y&quot;</span> <span class="pre">}}</span></tt> uses a Unix-style &#8220;pipe&#8221; (the &#8220;|&#8221;
character). This is called a template filter, and it&#8217;s a way to filter the value
of a variable. In this case, the date filter formats a Python datetime object in
the given format (as found in PHP&#8217;s date function).</p>
<p>You can chain together as many filters as you&#8217;d like. You can write <a class="reference internal" href="../howto/custom-template-tags.html#howto-writing-custom-template-filters"><em>custom
template filters</em></a>. You can write
<a class="reference internal" href="../howto/custom-template-tags.html"><em>custom template tags</em></a>, which run custom
Python code behind the scenes.</p>
<p>Finally, Django uses the concept of &#8220;template inheritance&#8221;. That&#8217;s what the
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">&quot;base.html&quot;</span> <span class="pre">%}</span></tt> does. It means &#8220;First load the template called
&#8216;base&#8217;, which has defined a bunch of blocks, and fill the blocks with the
following blocks.&#8221; In short, that lets you dramatically cut down on redundancy
in templates: each template has to define only what&#8217;s unique to that template.</p>
<p>Here&#8217;s what the &#8220;base.html&#8221; template, including the use of <a class="reference internal" href="../howto/static-files/index.html"><em>static files</em></a>, might look like:</p>
<div class="highlight-html+django"><div class="snippet-filename">mysite/templates/base.html</div>
<div class="highlight"><pre><span class="cp">{%</span> <span class="k">load</span> <span class="nv">staticfiles</span> <span class="cp">%}</span>
<span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;head&gt;</span>
    <span class="nt">&lt;title&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;/head&gt;</span>
<span class="nt">&lt;body&gt;</span>
    <span class="nt">&lt;img</span> <span class="na">src=</span><span class="s">&quot;</span><span class="cp">{%</span> <span class="k">static</span> <span class="s2">&quot;images/sitelogo.png&quot;</span> <span class="cp">%}</span><span class="s">&quot;</span> <span class="na">alt=</span><span class="s">&quot;Logo&quot;</span> <span class="nt">/&gt;</span>
    <span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
</pre></div>
</div>
<p>Simplistically, it defines the look-and-feel of the site (with the site&#8217;s logo),
and provides &#8220;holes&#8221; for child templates to fill. This makes a site redesign as
easy as changing a single file &#8211; the base template.</p>
<p>It also lets you create multiple versions of a site, with different base
templates, while reusing child templates. Django&#8217;s creators have used this
technique to create strikingly different mobile versions of sites &#8211; simply by
creating a new base template.</p>
<p>Note that you don&#8217;t have to use Django&#8217;s template system if you prefer another
system. While Django&#8217;s template system is particularly well-integrated with
Django&#8217;s model layer, nothing forces you to use it. For that matter, you don&#8217;t
have to use Django&#8217;s database API, either. You can use another database
abstraction layer, you can read XML files, you can read files off disk, or
anything you want. Each piece of Django &#8211; models, views, templates &#8211; is
decoupled from the next.</p>
</div>
<div class="section" id="s-this-is-just-the-surface">
<span id="this-is-just-the-surface"></span><h2>This is just the surface<a class="headerlink" href="#this-is-just-the-surface" title="Permalink to this headline">¶</a></h2>
<p>This has been only a quick overview of Django&#8217;s functionality. Some more useful
features:</p>
<ul class="simple">
<li>A <a class="reference internal" href="../topics/cache.html"><em>caching framework</em></a> that integrates with memcached
or other backends.</li>
<li>A <a class="reference internal" href="../ref/contrib/syndication.html"><em>syndication framework</em></a> that makes
creating RSS and Atom feeds as easy as writing a small Python class.</li>
<li>More sexy automatically-generated admin features &#8211; this overview barely
scratched the surface.</li>
</ul>
<p>The next obvious steps are for you to <a class="reference external" href="https://www.djangoproject.com/download/">download Django</a>, read <a class="reference internal" href="tutorial01.html"><em>the
tutorial</em></a> and join <a class="reference external" href="https://www.djangoproject.com/community/">the community</a>. Thanks for your
interest!</p>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Django at a glance</a><ul>
<li><a class="reference internal" href="#design-your-model">Design your model</a></li>
<li><a class="reference internal" href="#install-it">Install it</a></li>
<li><a class="reference internal" href="#enjoy-the-free-api">Enjoy the free API</a></li>
<li><a class="reference internal" href="#a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house">A dynamic admin interface: it&#8217;s not just scaffolding &#8211; it&#8217;s the whole house</a></li>
<li><a class="reference internal" href="#design-your-urls">Design your URLs</a></li>
<li><a class="reference internal" href="#write-your-views">Write your views</a></li>
<li><a class="reference internal" href="#design-your-templates">Design your templates</a></li>
<li><a class="reference internal" href="#this-is-just-the-surface">This is just the surface</a></li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="index.html">Getting started</a></li>
    
    
      <li>Next: <a href="install.html">Quick install guide</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="index.html">Getting started</a>
        
        <ul><li>Django at a glance</li></ul>
        </li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../_sources/intro/overview.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="Getting started">previous</a>
     |
    <a href="index.html" title="Getting started" accesskey="U">up</a>
   |
    <a href="install.html" title="Quick install guide">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>